<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine manual.-*-Text-*- -->

<div class='chapter' id='17'>17. Areas</div><p class='cindent'><!-- area -->

<!-- What is in all value cells and function cells of the area names? -->

[Note: this chapter will be completely rewritten in the next edition
of this manual, to reflect the existence of the garbage collector.
The present chapter is very incomplete.]

Storage in the Lisp machine is divided into <!-- open: 1, close: 0 --><font class="italic">areas</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED -->.
Each area contains related objects, of any type.  Areas are intended to give the
user control over the paging behavior of his program, among other
things.  By putting related data together, locality can be greatly
increased.  Whenever a new object is created, for instance with <!-- open: 2, close: 1 --><font class="lisp">cons</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED -->,
the area to be used can optionally be specified.  There is a default
Working Storage area which collects those objects which the user has
not chosen to control explicitly. 

	Areas also give the user a handle to control the garbage
collector.  Some areas can be declared to be "static", which means that
they change slowly and the garbage collector should not attempt to
reclaim any space in them.  This can eliminate a lot of useless
copying.  All pointers out of a static area can be collected into an
"exit vector", eliminating any need for the garbage collector to look
at that area.  As an important example, an English-language dictionary
can be kept inside the Lisp without adversely affecting the speed of
garbage collection.  A "static" area can be explicitly
garbage-collected at infrequent intervals when it is believed that that
might be worthwhile. 

	Each area can potentially have a different storage discipline,
a different paging algorithm, and even a different data representation. 
The microcode will dispatch on an attribute of the area at the
appropriate times.  The structure of the machine makes the performance
cost of these features negligible; information about areas is stored
in extra bits in the memory mapping hardware where it can be quickly
dispatched on by the microcode.  These dispatches usually have to be
done anyway to make the garbage collector work, and to implement
invisible pointers. 

	Since the garbage collector is not yet implemented, the features
mentioned in the previous two paragraphs are not either.  Also, with
the implementation of the garbage collector will come a new, more sophisticated
area scheme.  The two most visible effects of the new scheme will be
that garbage will be collected, and that areas will be able to shrink
and grow.  When this happens, it will be documented; stay tuned.  Most of this
chapter will become inoperative at this time, so don't depend on it.

	Each area has a name and a number.  The name is a symbol whose value
is the number.  The number is an index into various internal tables.  Normally
the name is treated as a special variable, so the number is what is given
as an argument to a function that takes an area as an argument.
Thus, areas are not Lisp objects.

The following variables hold the areas most often used:

<div class='defvar' id='default-cons-area'><font class='exdent'><font class='funcname' id='default-cons-area'>default-cons-area</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->The value of this variable is the number of the area to which all of the creators
of conses (<!-- open: 3, close: 2 --><font class="lisp">cons, xcons, list, append</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED -->, etc.) use by default.
It is initially the number of <!-- open: 4, close: 3 --><font class="lisp">working-storage-area</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED -->.
Note that you can either bind this variable or use functions such as
<!-- open: 5, close: 4 --><font class="lisp">cons-in-area</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED --> (see <font color='red'>LINK:(</font>cons-in-area-fun)) which take an area as an explicit argument.
</div>

<div class='defvar' id='default-array-area'><font class='exdent'><font class='funcname' id='default-array-area'>default-array-area</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->The value of this variable is the number of the area which
<!-- open: 6, close: 5 --><font class="lisp">make-array</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> uses by default.  It is initially the number of
<!-- open: 7, close: 6 --><font class="lisp">working-storage-area</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='make-area'>
  <font class='exdent'>
    <font class='funcname'>make-area </font>
    <font class='italic' color='purple'>&rest keywords</font>
  </font><br>
Creates a new area, whose name and attributes are specified by the keywords.
You must specify a symbol as a name; the symbol will be <!-- open: 8, close: 7 --><font class="lisp">setq</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED -->'ed to
the area-number of the new area, and that number will also be returned.
The arguments are taken in pairs, the first being a keyword and the second
a "value" for that keyword.  The following keywords exist:
<table>
<tr valign='top'>
<td><font class='lisp'> :name</font></td><td>A symbol which will be the name of the area.  This item is required.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :size</font></td><td>The maximum allowed size of the area, in words.  Defaults to infinite.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :region-size</font></td><td>The approximate size, in words, for regions within this area.  The default
is the area size if a <!-- open: 9, close: 8 --><font class="lisp">:size</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> argument was given, otherwise a suitable
medium size.  Note that if you specify <!-- open: 10, close: 9 --><font class="lisp">:size</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> and not <!-- open: 11, close: 10 --><font class="lisp">:region-size</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED -->,
the area will have exactly one region.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :representation</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The type of object to be contained in the area's initial region.
The argument to this keyword can be <!-- open: 12, close: 11 --><font class="lisp">:list</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 13, close: 12 --><font class="lisp">:structure</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED -->, or a numeric code.
<!-- open: 14, close: 13 --><font class="lisp">:structure</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> is the default.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :gc</font></td><td>The type of garbage-collection to be employed.  The choices are <!-- open: 15, close: 14 --><font class="lisp">:dynamic</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED -->
(which is the default) and <!-- open: 16, close: 15 --><font class="lisp">:static</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 17, close: 16 --><font class="lisp">:static</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED --> means that the area will
not be copied by the garbage collector, and nothing in the area or pointed to by
the area will ever be reclaimed.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :read-only</font></td><td>With an argument of <!-- open: 18, close: 17 --><font class="lisp">t</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED -->, causes the area to be made <!-- open: 19, close: 18 --><font class="italic">read-only</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :pdl</font></td><td>With an argument of <!-- open: 20, close: 19 --><font class="lisp">t</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED -->, makes the area suitable for storing
regular-pdls of stacks.  This is a special attribute due to the
pdl-buffer hardware.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :compact-cons</font></td><td>With an argument of <!-- open: 21, close: 20 --><font class="lisp">t</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED -->, enables the <!-- open: 22, close: 21 --><font class="italic">at present unimplemented</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->
feature that <!-- open: 23, close: 22 --><font class="lisp">cons</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED --> will create cdr-coded list-structure when possible.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> sys:%%region-map-bits</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Lets you specify the <!-- open: 24, close: 23 --><font class="italic">map bits</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED --> explicitly, overriding the specification
from the other keywords.  This is for special hacks only.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> sys:%%region-space-type</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Lets you specify the <!-- open: 25, close: 24 --><font class="italic">space type</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED --> explicitly, overriding the specification
from the other keywords.  This is for special hacks only.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> sys:%%region-scavenge-enable</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Lets you override the scavenge-enable bit explicitly.  Don't mess with this!
</td></tr><!-- item_ --></table><!-- end table -->


<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(make-area ':name 'foo-area
	   ':gc ':dynamic
	   ':representation ':list)
</pre>
</div>

<div class='defvar' id='area-list'><font class='exdent'><font class='funcname' id='area-list'>area-list</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->The value of <!-- open: 26, close: 25 --><font class="lisp">area-list</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED --> is a list of the names of all existing areas.
This list shares storage with the internal area name table, so you should
not change it.
</div>

<div class='defun' id='%area-number'>
  <font class='exdent'>
    <font class='funcname'>%area-number </font>
    <font class='italic' color='purple'>pointer</font>
  </font><br>
Returns the number of the area to which <!-- open: 27, close: 26 --><font class="italic">pointer</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED --> points, or <!-- open: 28, close: 27 --><font class="lisp">nil</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED --> if
it does not point within any known area.  The data-type of <!-- open: 29, close: 28 --><font class="italic">pointer</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED -->
is ignored.
</div>

<div class='defun' id='%region-number'>
  <font class='exdent'>
    <font class='funcname'>%region-number </font>
    <font class='italic' color='purple'>pointer</font>
  </font><br>
Returns the number of the region to which <!-- open: 30, close: 29 --><font class="italic">pointer</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --> points, or <!-- open: 31, close: 30 --><font class="lisp">nil</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> if
it does not point within any known region.  The data-type of <!-- open: 32, close: 31 --><font class="italic">pointer</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED -->
is ignored.  Regions will be explained later.
</div>
	
We will now list those areas with which the user may need to be concerned.
This section will be expanded later.

<div class='defvar' id='area-name'><font class='exdent'><font class='funcname' id='area-name'>area-name</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->Indexed by area number.  Contains the area's name (a symbol).
</div>

<div class='defun' id='area-name'>
  <font class='exdent'>
    <font class='funcname'>area-name </font>
    <font class='italic' color='purple'>pointer</font>
  </font><br>
The function definition of <!-- open: 33, close: 32 --><font class="lisp">area-name</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED --> is an array of area names,
indexed by area numbers.
</div>

<div class='defvar' id='working-storage-area'><font class='exdent'><font class='funcname' id='working-storage-area'>working-storage-area</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->This is the normal value of <!-- open: 34, close: 33 --><font class="lisp">default-cons-area</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 35, close: 34 --><font class="lisp">default-array-area</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED -->.
Most working data are consed in this area.
</div>

<div class='defvar' id='permanent-storage-area'><font class='exdent'><font class='funcname' id='permanent-storage-area'>permanent-storage-area</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->This is to be used for "permanent" data, which will (almost) never become
garbage.  Unlike <!-- open: 36, close: 35 --><font class="lisp">woring-storage-area</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED -->, the contents of this area
are not continually copied by the garbage collector.
</div>

<div class='defvar' id='sys:p-n-string'><font class='exdent'><font class='funcname' id='sys:p-n-string'>sys:p-n-string</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->Print names are stored here.
</div>

<div class='defvar' id='sys:nr-sym'><font class='exdent'><font class='funcname' id='sys:nr-sym'>sys:nr-sym</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->This contains most of the symbols in the Lisp world, except <!-- open: 37, close: 36 --><font class="lisp">t</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 38, close: 37 --><font class="lisp">nil</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defvar' id='macro-compiled-program'><font class='exdent'><font class='funcname' id='macro-compiled-program'>macro-compiled-program</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->FEFs are put here by the compiler and by <!-- open: 39, close: 38 --><font class="lisp">fasload</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED -->.
</div>
<!-- eof -->
</body>
</html>

